Agent Reference
A dense, copy-friendly reference for AI coding agents (Claude Code, Cursor, and similar tools) integrating against OctoPos.
The full text of this page is the canonical reference. If you want it as a single plain-text file for LLM ingestion, see Build with AI — llms-full.txt is to be updated.
Authentication
EVM surface — public, no authentication. All endpoints accept requests without headers.
Stellar surface — public read endpoints (/v1/positions/:address, /v1/contracts/:address, /v1/protocols) accept requests without authentication. Endpoints that read subscriber-only data (/v1/keys/me/*, /v1/subscription/*) require an API key. The key is sent as Authorization: Bearer <key> for authenticated requests, and HMAC-signed for webhooks. See Subscriptions.
x402 — for metered access on the Stellar side, the API responds with 402 Payment Required and a payment challenge when an unauthenticated request hits a paid endpoint. The client pays the challenge (USDC on Base) and retries. x402 is supported out of the box — no SDK needed.
Base URLs
# Stellar API (production)
https://api-octopos-mainnet.crediolabs.ai
# EVM API (production)
https://api-evm-octopos-mainnet.crediolabs.ai
# Brand fallback (same bundles, different zone)
https://api-octopos-mainnet.untangled.finance
https://api-evm-octopos-mainnet.untangled.finance
Stellar paths are mounted under /v1/*. EVM paths are also under /v1/*. Both APIs are HTTPS only.
EVM endpoints (stable)
| Method | Path | Description |
|---|---|---|
GET | /v1/evm/balances/:address | Multi-chain ERC-20 + native balances. Defaults to 13 chains. |
GET | /v1/evm/stablecoins/:address | Stablecoin-only filter on balances. |
GET | /v1/evm/activity/:address | Token transfers + native txs, with activity_type filter. |
GET | /v1/evm/transactions/:address | Raw txs with optional 4byte decode via ?decode=true. |
GET | /v1/evm/defi/positions/:address | DeFi positions per chain. Ethereum only. |
GET | /v1/evm/supported-chains | List of 16 supported chains with per-endpoint supported flags. |
GET | /v1/evm/subscriptions | List webhooks for the caller. |
POST | /v1/evm/subscriptions | Create a webhook. |
GET | /v1/evm/subscriptions/:id | Read a single webhook. |
PATCH | /v1/evm/subscriptions/:id | Update a webhook. |
DELETE | /v1/evm/subscriptions/:id | Delete a webhook. |
GET | /healthz | Plain-text ok health check. |
Full per-endpoint description, request/response examples, and known limitations: OctoPos EVM capabilities.
Stellar endpoints (stable)
| Method | Path | Description |
|---|---|---|
GET | /v1/health | Health + last snapshot timestamp. |
GET | /v1/protocols | Catalog of supported Stellar protocols. |
GET | /v1/protocols/:id | Single protocol detail. |
GET | /v1/positions/:address | All DeFi positions for a Stellar address. |
GET | /v1/positions/:address/protocols | Per-protocol breakdown. |
GET | /v1/positions/:address/history | Historical snapshots. |
GET | /v1/positions/:address/summary | Aggregated portfolio value + risk summary. |
GET | /v1/positions/:address/yield | Unclaimed yield + accrued interest. |
GET | /v1/positions/:address/events | Position lifecycle events. |
GET | /v1/contracts/:address | Contract-level detail. |
GET | /v1/contracts/:address/resolve | Reverse-resolve a Stellar contract to a known protocol. |
GET | /v1/contracts/:address/history | Contract interaction history. |
GET | /v1/streaming/:address/history | NDJSON streaming of historical position snapshots. |
POST | /v1/txb/simulate | Simulate a Soroban transaction. |
GET | /v1/txb/:ledger | Transaction builder state for a ledger. |
GET | /v1/openapi.json | OpenAPI 3.0.3 spec for the entire Stellar API. |
POST | /v1/subscription/subscribe | Start a paid subscription. |
GET | /v1/subscription/status | Read subscription state. |
POST | /v1/subscription/confirm-payment | Confirm an x402 payment. |
For full per-endpoint docs: DeFi Positions API (Stellar).
Webhooks
Both surfaces support webhooks for change notifications.
EVM — POST to /v1/evm/subscriptions with { address, chain_ids, webhook_url, event_types }. Signed with HMAC-SHA256, retries with exponential backoff.
Stellar — POST to /v1/webhooks/{goldsky,slack,x402}. See Stellar deployment docs.
Pagination
To be updated. EVM endpoints accept offset and limit query params; default limit=100, max 1000 for balances, 100 for activity, 100 for transactions. The API does not return a cursor — concatenate until you receive fewer items than the limit, or until a next_offset field is included in the response (planned).
Error handling
To be updated. The API returns standard HTTP status codes:
| Code | Meaning | Action |
|---|---|---|
200 | Success | Parse the response body. |
400 | Malformed request | Check query params, address format, chain_ids. |
402 | Payment required (Stellar paid endpoints) | Resolve the x402 challenge and retry. |
404 | Address has no activity on any supported chain | Treat as empty portfolio. |
429 | Rate limited | Back off and retry after Retry-After header. |
500 | Upstream RPC failure | Retry with backoff; one or more chain RPCs may be down. |
503 | Worker isolate restarting | Retry; transient. |
Compute units / quota
To be updated. EVM API rate limits are in-memory and reset on Worker isolate restart. There is no published CU cost model. Stellar API uses HMAC key lookup with short-TTL KV cache; subscriber-tier requests are billed by x402 payment, public read endpoints are unmetered.
Chain reference (EVM)
16 supported chains, 9 deferred. The full table is on OctoPos EVM supported chains. Quick reference for the 13 default-tag chains that /v1/evm/balances expands to without chain_ids:
| Chain ID | Name |
|---|---|
| 1 | Ethereum |
| 10 | OP Mainnet |
| 56 | BNB Smart Chain |
| 100 | Gnosis |
| 137 | Polygon |
| 324 | zkSync Era |
| 999 | HyperEVM |
| 8453 | Base |
| 42161 | Arbitrum One |
| 42220 | Celo |
| 43114 | Avalanche C-Chain |
| 81457 | Blast |
| 7777777 | Zora (balances only, no DeFi positions) |
Protocol reference (Stellar)
| Protocol | Adapter | Notes |
|---|---|---|
| Blend | Lending | All pools, all position types. Health factor with per-pool reserve factors. |
| Aquarius | AMM | LP positions, CLPs, staking. |
| SoroSwap | AMM | LP positions. |
| Phoenix | AMM | LP positions. |
| FxDAO | Vault | Stablecoin vault shares. |
| Untangled Vault | ERC-4626 vault | Share balance, NAV-based pricing. |
| Untangled Loop | Leveraged positions | Synthetic long/short on Blend + Aquarius. |
| Native XLM | Wallet | All trustline assets. |
Response shapes
To be updated. Representative shapes:
EVM /v1/evm/balances/:address — see OctoPos EVM capabilities.
Stellar /v1/positions/:address — see DeFi Positions API (Stellar).
Common workflows
Combined Stellar + EVM portfolio
OctoPos is the only API that returns normalised positions for both a Stellar G... address and an EVM 0x... address in the same response shape. The use case: a wallet that holds a user's Stellar and EVM activity in one view.
# Stellar positions
curl https://api-octopos-mainnet.crediolabs.ai/v1/positions/GABC.../summary
# EVM positions
curl https://api-evm-octopos-mainnet.crediolabs.ai/v1/evm/balances/0x...?chain_ids=1
# Both responses carry a `total_usd` field; sum them client-side for a unified portfolio.
To be updated: a single endpoint that takes both addresses and returns one merged position view.
Real-time activity feed for an EVM address
# Recent token swaps, top 10
curl 'https://api-evm-octopos-mainnet.crediolabs.ai/v1/evm/activity/0x...?activity_type=swap&limit=10'
Subscribe to balance changes
curl -X POST https://api-evm-octopos-mainnet.crediolabs.ai/v1/evm/subscriptions \
-H 'content-type: application/json' \
-d '{
"address": "0x...",
"chain_ids": [1],
"webhook_url": "https://your.app/hook",
"event_types": ["balance_change"]
}'
Cross-check a Stellar address against on-chain reality
curl https://api-octopos-mainnet.crediolabs.ai/v1/positions/GABC.../contracts
# Returns per-protocol breakdown: which Blend pool, which Aquarius LP, etc.
Rules
Always:
- Pass
chain_idsexplicitly when calling/v1/evm/balancesto avoid scanning all 13 default-tag chains. - URL-encode the path (use
%20for spaces in/v1/evm/balances/0x...is N/A; the address is hex). Spaces only matter in query string values. - Use the right base URL:
api-evm-octopos-mainnet.crediolabs.aifor EVM,api-octopos-mainnet.crediolabs.aifor Stellar.
Ask first:
- Whether the DeFi positions endpoint (Ethereum only) covers the chain you need. Multi-chain DeFi is not yet supported.
- Whether the address has been seen before — first-time queries are slower (live fetch from RPC).
Never:
- Construct manual offsets. The pagination model is to be updated; for now, request
limit=1000and stop when fewer items return. - Assume chain names are accepted in
chain_ids. Use numeric IDs only (1,137,42161). - Call the EVM API from a browser without checking CORS first.
What this API does NOT support
- No writes. OctoPos is read-only — there is no way to send a transaction, sign a message, or move funds via OctoPos. Use the protocol's own UI or a wallet.
- No WebSockets. Streaming is via NDJSON HTTP responses on the Stellar side (
/v1/streaming/:address/history). - No ENS / SNS / human-readable name resolution. Pass raw addresses.
- No on-chain transaction broadcasting on the EVM side. (The Stellar API exposes
POST /v1/txb/simulatefor simulation only.) - No real-time push updates. Subscribe to webhooks and consume HTTP POSTs.
Links
- Build with AI overview — quick-start guide for LLMs
- OctoPos EVM overview — V8.3, deployed URLs, architecture
- OctoPos EVM capabilities — per-endpoint reference
- OctoPos EVM supported chains — 16 + 9 deferred
- DeFi Positions API (Stellar) — Stellar surface
- OpenAPI spec (Stellar) — generated client source
- Untangled OctoPos engineering docs (feat/evm-port) — chain-by-chain adapter matrix